home *** CD-ROM | disk | FTP | other *** search
/ Adobe Graphics & Publishing SDK 1996 December / Adobe Graphics & Publishing SDK 1996 December.iso / pc / pm65sdk / sourcecode / includes / hcmplugs.h < prev    next >
C/C++ Source or Header  |  1996-11-18  |  16KB  |  409 lines
  1. /************************************************************************************
  2.  *    hcmplugs.h
  3.  *        This file contains interfaces that plug-in writers can use to access
  4.  *        HyperContent. 
  5.  *        
  6.  *        Attempts are made here to indicate by parameter name whether it's an in, 
  7.  *        out, or inout parameter.
  8.  *    
  9.  *    Copyright:    ⌐ 1996 by Adobe Systems, Inc., all rights reserved.
  10.  *
  11.  * $Revision:   1.5  $
  12.  *
  13.  *
  14.  ************************************************************************************/
  15.  
  16.  
  17.  
  18. #if !defined( HCMPLUGS_H )
  19.     #define HCMPLUGS_H
  20.     
  21.  
  22.  
  23.     /************************************************************************************
  24.                                     Dependent headers
  25.     ************************************************************************************/
  26.  
  27.     #if !defined( __PageMakerTypes__ )
  28.         #include "PMTypes.h"
  29.     #endif
  30.  
  31.         //
  32.         // this project
  33.         //
  34.     #if !defined( HCMDEFS_H )
  35.         #include "hcmdefs.h"
  36.     #endif /* HCMDEFS_H */
  37.     
  38.     #if !defined( HCMERRS_H )
  39.         #include "hcmerrs.h"
  40.     #endif /* HCMERRS_H */
  41.     
  42.     #if !defined( HCMTYPES_H )
  43.         #include "hcmtypes.h"
  44.     #endif /* HCMTYPES_H */
  45.     
  46.  
  47.  
  48.     /************************************************************************************
  49.                                     Forward declarations
  50.     ************************************************************************************/
  51.     #if defined( __cplusplus )
  52.         class CHcmPlugInContentHandler;
  53.     #endif /* __cplusplus */
  54.     
  55.  
  56.  
  57.     /************************************************************************************
  58.                                         Public types
  59.     ************************************************************************************/
  60.         //
  61.         // CHandlerDeathProcPtr
  62.         //
  63.         // this is a notification proc used to informed registered clients of this
  64.         //    interface that the CHcmContentHandler they have is now dead and gone.  It's
  65.         //    probably in your best interest to provide this function ptr at register time.
  66.         //    This function may also be called on a thread which is why it's a one-way
  67.         //    notification.
  68.         //
  69.         //    Macintosh client note -- This function is called directly without going 
  70.         //    through the mixed mode manager via CallUniversalProc.  This means that the
  71.         //    function you provide must be native to the platform it's running on and
  72.         //    not emulated (e.g. 68k running on a PowerPC).
  73.         //
  74.     #if defined( __cplusplus )
  75.         typedef void  (*CHandlerDeathProcPtr)( CHcmPlugInContentHandler *  inCHandlerPtr );
  76.     #endif /* __cplusplus */
  77.  
  78.         //
  79.         // Bounding Box record
  80.         //
  81.     struct HcmBoundingBoxRec
  82.     {
  83.         HcmPmLocationEnum  m_PageNumber;
  84.         #if defined( MACINTOSH )
  85.             Rect  m_BoundingBox;
  86.         #else /* MACINTOSH */
  87.             RECT  m_BoundingBox;
  88.         #endif /* MACINTOSH */
  89.     }; // HcmBoundingBoxRec
  90.     typedef struct HcmBoundingBoxRec HcmBoundingBoxRec;
  91.  
  92.         //
  93.         // Bounding Box list header
  94.         //
  95.     struct HcmBoundingBoxHdrRec
  96.     {
  97.         UINT32  m_ElementCount;
  98.         HcmBoundingBoxRec *  m_BoundingBoxRecPtr;
  99.     }; // HcmBoundingBoxHdrRec
  100.     typedef struct HcmBoundingBoxHdrRec HcmBoundingBoxHdrRec;
  101.     
  102.  
  103.  
  104.     /************************************************************************************
  105.                                     Public __cplusplus definitions
  106.     ************************************************************************************/
  107.     #if defined( __cplusplus )
  108.  
  109.             //
  110.             // CHcmPlugInRegistry
  111.             //
  112.             //    This is the object where clients come for contenthandler objects.
  113.             //
  114.         class CHcmPlugInRegistry
  115.         {
  116.                             //
  117.                             // public methods
  118.                             //
  119.             public:
  120.                     //
  121.                     // content type client registry
  122.                     //
  123.                     //    This is the member function that clients use to obtain
  124.                     //    content handler objects.  Note the CHandlerDeathProcPtr 
  125.                     //    parameter and it's importance -- see the note above.
  126.                     //
  127.                 virtual HcmErr  ContentTypeRegister(
  128.                                 const HcmCallerIdEnum  inUniqueCallerId, 
  129.                                 const char *  inContentTypePtr, 
  130.                                 CHandlerDeathProcPtr  inNotifyProcPtr, 
  131.                                 CHcmPlugInContentHandler **  outCHandlerPtr ) = 0;
  132.     
  133.                     //
  134.                     // un-registering of clients
  135.                     //
  136.                     //    This is the member function that clients can use to dump
  137.                     //    the content handler object.
  138.                     //
  139.                 virtual HcmErr  ContentTypeUnregister(
  140.                                 const HcmCallerIdEnum  inUniqueCallerId, 
  141.                                 const char * inContentTypePtr ) = 0;
  142.         }; /* class CHcmPlugInRegistry */
  143.  
  144.  
  145.  
  146.             //
  147.             // CHcmPlugInContentHandler
  148.             //
  149.             //    This is the object that clients use to talk to the HCM.
  150.             //
  151.         class CHcmPlugInContentHandler
  152.         {
  153.                             //
  154.                             // public methods
  155.                             //
  156.             public:
  157.                     //
  158.                     // destroys the bounding box header record.
  159.                     //
  160.                 virtual void  BoundingBoxHdrRecDestroy( HcmBoundingBoxHdrRec *  inPtr ) = 0;
  161.                 
  162.                     //
  163.                     // use this to create an object
  164.                     //
  165.                 virtual HcmErr  Create(
  166.                                 HcmObjectCreateDescRec * inObjectDescriptionPtr, 
  167.                                 HcmObjectId *  outCreatedObjectId ) = 0;
  168.     
  169.                     //
  170.                     // use one of these to delete an object
  171.                     //
  172.                 virtual HcmErr  Delete( const HcmObjectId  inObjectId ) = 0;
  173.                 virtual HcmErr  Delete(
  174.                                 HcmPmUniqueRec *  inObjectToDeletePtr, 
  175.                                 HcmObjectTypeEnum  inKindOfObject ) = 0;
  176.     
  177.                     //
  178.                     // Destroys the buffer allocated by DisplayNameGet.
  179.                     //
  180.                 virtual HcmErr  DisplayNameBufferDestroy( 
  181.                                 char *  inBufferPtr ) = 0;
  182.     
  183.                     //
  184.                     // returns the display name, ASCII CString, of the indicated
  185.                     //  object into a buffer allocated by the caller.
  186.                     //
  187.                 virtual HcmErr  DisplayNameGet( 
  188.                                 const HcmObjectId  inObjectId, 
  189.                                 char **  outNamePtr ) = 0;
  190.                     //
  191.                     // sets the display name
  192.                     //
  193.                 virtual HcmErr  DisplayNameSet(
  194.                                 const HcmObjectId inObjectId, 
  195.                                 char *  inNewNamePtr ) = 0;
  196.  
  197.                             //
  198.                             // getting HcmObjectIds from other data
  199.                             //
  200.                     //
  201.                     // by HcmPmUniqueRec.  Since a PageMaker segment can be 
  202.                     //    BOTH a hyperlink and an anchor OR simply just a storage-only
  203.                     //    object, this function needs 3 pointers to indicate the segment
  204.                     //    state via these IDs.
  205.                     //
  206.                 virtual HcmErr  HcmObjectIdGet(
  207.                                 HcmPmUniqueRec *  inPmUniqueRecPtr, 
  208.                                 HcmObjectId *  outAnchorObjectIdPtr, 
  209.                                 HcmObjectId *  outHyperlinkObjectIdPtr, 
  210.                                 HcmObjectId *  outStorageOnlyObjectIdPtr ) = 0;
  211.                     //
  212.                     // by display name (palette name)
  213.                     //
  214.                 virtual HcmErr  HcmObjectIdGet(
  215.                                 char *  inName, 
  216.                                 HcmObjectId *  outObjectId ) = 0;
  217.     
  218.                     //
  219.                     // returns the Hcm-type of the indicated object.
  220.                     //
  221.                 virtual HcmErr  HyperContentTypeGet(
  222.                                 const HcmObjectId  inObjectId, 
  223.                                 HcmObjectTypeEnum *  outObjectType ) = 0;
  224.     
  225.                     //
  226.                     // utility to determine kind of segment that data belongs to.
  227.                     //
  228.                 virtual HcmErr  IsPmTextSegment(
  229.                                 const HcmObjectId  inObjectId, 
  230.                                 PMBool *  outIsTextSegment ) = 0;
  231.     
  232.                     //
  233.                     // determines if the passed in type is a valid anchor
  234.                     //
  235.                 virtual PMBool  IsValidAnchorType( HcmObjectTypeEnum  inType ) = 0;
  236.     
  237.                     //
  238.                     // determines if the passed in type is a valid hyperlink
  239.                     //
  240.                 virtual PMBool  IsValidHyperlinkType( HcmObjectTypeEnum  inType ) = 0;
  241.     
  242.                     //
  243.                     // determines if the passed in type is a valid StorageOnly
  244.                     //
  245.                 virtual PMBool  IsValidStorageOnlyType( HcmObjectTypeEnum  inType ) = 0;
  246.     
  247.                     //
  248.                     // gets the pagemaker info of the indicated object.
  249.                     //
  250.                 virtual HcmErr  PageMakerInfoGet(
  251.                                 const HcmObjectId  inObjectId, 
  252.                                 HcmPmUniqueRec *  outPmUniqueRecPtr ) = 0;
  253.  
  254.                     //
  255.                     // sets the pagemaker info of the indicated object.
  256.                     //
  257.                 virtual HcmErr  PageMakerInfoSet(
  258.                                 const HcmObjectId  inObjectId, 
  259.                                 HcmPmUniqueRec *  inPmUniqueRecPtr ) = 0;
  260.     
  261.                     //
  262.                     // just returns the page number of the object.
  263.                     //
  264.                 virtual HcmErr  PageMakerLocationGet(
  265.                                 const HcmObjectId  inObjectId,
  266.                                 HcmPmLocationEnum *  outLocation ) = 0;
  267.  
  268.                     //
  269.                     // SIDE EFFECT -- To find out what page it's on, this
  270.                     //    code uses the Hypertext routine that jumps to the
  271.                     //    page.
  272.                     //
  273.                 virtual HcmErr  PageMakerLocationGet(
  274.                                 const HcmObjectId  inObjectId,
  275.                                 HcmPmLocationEnum *  outLocation,
  276.                                 INT32 *  outItemTop,
  277.                                 INT32 *  outItemLeft ) = 0;
  278.  
  279.                     //
  280.                     // Don't forget after calling this to destroy the bounding
  281.                     //    box record allocated to avoid a memory leak.
  282.                     //    Currently -- BoundingBoxHdrRecDestroy.
  283.                     //
  284.                 virtual HcmErr  PageMakerLocationGet(
  285.                                 const HcmObjectId  inObjectId,
  286.                                 HcmBoundingBoxHdrRec **  outBBoxHdrRecPtr ) = 0;
  287.  
  288.                     //
  289.                     // this routine asks the HCM if inPmUniqueRecPtr says that there
  290.                     //    is anchor info attached to the pm object.
  291.                     //
  292.                 virtual PMBool  PageMakerSegmentHasAnchorInfo(
  293.                                 HcmPmUniqueRec *  inPmUniqueRecPtr ) = 0;
  294.  
  295.                     //
  296.                     // this routine asks the HCM if inPmUniqueRecPtr says that there
  297.                     //    is hyperlink info attached to the pm object.
  298.                     //
  299.                 virtual PMBool  PageMakerSegmentHasHyperlinkInfo(
  300.                                 HcmPmUniqueRec *  inPmUniqueRecPtr ) = 0;
  301.  
  302.                     //
  303.                     // this routine asks the HCM if inPmUniqueRecPtr says that there
  304.                     //    is StorageOnly info attached to the pm object.
  305.                     //
  306.                 virtual PMBool  PageMakerSegmentHasStorageOnlyInfo(
  307.                                 HcmPmUniqueRec *  inPmUniqueRecPtr ) = 0;
  308.  
  309.                     //
  310.                     // determines if the passed segment has hypercontent
  311.                     //
  312.                 virtual PMBool  PageMakerSegmentHasHyperContent(
  313.                                 HcmPmUniqueRec *  inPmUniqueRecPtr ) = 0;
  314.     
  315.                     //
  316.                     // caller allocates a buffer large enough to hold the 
  317.                     //  data, this function fills it.  
  318.                     //
  319.                 virtual HcmErr  PrivateDataRead(
  320.                                 const HcmObjectId  inObjectId, 
  321.                                 char *  outBuffer, 
  322.                                 UINT32 * inoutHowMuchToRead ) = 0;
  323.     
  324.                     //
  325.                     // returns the size of the objects data
  326.                     //
  327.                 virtual HcmErr  PrivateDataSizeGet( 
  328.                                 const HcmObjectId  inObjectId, 
  329.                                 UINT32 *  outHowBig ) = 0;
  330.     
  331.                     //
  332.                     // caller allocates a buffer large enough to hold the 
  333.                     //  data, this function writes with it.  
  334.                     //
  335.                 virtual HcmErr  PrivateDataWrite( 
  336.                                 const HcmObjectId  inObjectId, 
  337.                                 char *  inBuffer, 
  338.                                 UINT32 *  inoutHowMuchToWrite ) = 0;
  339.     
  340.                     //
  341.                     // caller allocates a buffer large enough to hold the 
  342.                     //  data, this function fills it.  
  343.                     //
  344.                 virtual HcmErr  PubPrefsRead( 
  345.                                 char *  outBuffer, 
  346.                                 UINT32 *  inoutHowMuchToRead ) = 0;
  347.     
  348.                     //
  349.                     // returns the size of the preference info
  350.                     //
  351.                 virtual HcmErr  PubPrefsSizeGet( UINT32 *  outHowBig ) = 0;
  352.     
  353.                     //
  354.                     // caller allocates a buffer large enough to hold the 
  355.                     //  data, this function writes with it.  
  356.                     //
  357.                 virtual HcmErr  PubPrefsWrite( 
  358.                                 char *  inBuffer, 
  359.                                 UINT32 *  inoutHowMuchToWrite ) = 0;
  360.     
  361.                     //
  362.                     // how to break relationships.
  363.                     //
  364.                 virtual HcmErr  RelationshipBreakAll( const HcmObjectId  inSource ) = 0;
  365.                 virtual HcmErr  RelationshipBreakOne(
  366.                                 const HcmObjectId  inSource, 
  367.                                 const HcmObjectId  inDestination ) = 0;
  368.      
  369.                     //
  370.                     // This is called by clients to destroy the array allocated by 
  371.                     // RelationshipGet
  372.                     //
  373.                 virtual HcmErr  RelationshipArrayDestroy(
  374.                                 HcmObjectId *  inDestinationArray ) = 0;
  375.                     //
  376.                     // how to iterate relationships.  Returns an array of 
  377.                     //  HcmObjectIds that this item points to.  Format is a 
  378.                     //    count followed by the ids.  Caller is responsible
  379.                     //    for calling RelationshipArrayDestroy on the array passed back.
  380.                     //
  381.                 virtual HcmErr  RelationshipGet(
  382.                                 const HcmObjectId  inSource, 
  383.                                 HcmObjectId **  outDestinationArray ) = 0;
  384.                     //
  385.                     // how to iterate relationships.  Returns an array of 
  386.                     //  HcmObjectIds that this item points to.  Format is a 
  387.                     //    count followed by the ids.  Caller is responsible
  388.                     //    for calling RelationshipArrayDestroy on the array passed back.
  389.                     //
  390.                     //    This overridden function only looks up anchors.
  391.                     //
  392.                 virtual HcmErr  RelationshipGet(
  393.                                 HcmPmUniqueRec *  inPmUniqueRecPtr, 
  394.                                 HcmObjectId **  outDestinationArray ) = 0;
  395.      
  396.                     //
  397.                     // how to make relationships.
  398.                     //
  399.                 virtual HcmErr  RelationshipMake(
  400.                                 const HcmObjectId  inSource, 
  401.                                 const HcmObjectId  inDestination ) = 0;
  402.         }; /* class CHcmPlugInContentHandler */
  403.  
  404.     #endif /* __cplusplus */
  405.  
  406.  
  407.  
  408. #endif /* HCMPLUGS_H */
  409.